<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html version="4.01"><head><title>[retawq] Compile-Time Configuration
Options</title></head>
<body text="#000000" bgcolor="#cccccc" link="#0000ff" vlink="#551a8b"
alink="#551a8b" lang="en">
<center><b><font size="+2">retawq Documentation</font><br><font
size="+1">Compile-Time Configuration Options</font></b></center>

<p><a name="intro"></a><b>Introduction</b></p>

<p>For configuring retawq before building the program ("compile-time
configuration"), both a "classical" Makefile and a more modern/portable
configure script are supported.</p>

<ul><li><b>classical Makefile</b> - you can change the options manually in the
file Makefile using a text editor. The compile-time configuration option names
begin with "OPTION_".</li>
<li><b>configure script</b> - you can specify the compile-time configuration
options as command-line arguments for the configure script. The arguments begin
with "--enable-", "--disable-" or "--set-"; in the description below, the value
"1" usually corresponds to "enabled", "0" to "disabled". You can get a list of
all script options with "./configure --help".</li>
</ul>

<p>If you're confused by all those options, compile the program with the
default configuration and work with it to get used to it first, e.g. as
described in the <a href="user_guide.html">user guide</a>. If compiling with
the default configuration fails, you might just have to set OPTION_TG to
"curses" and/or OPTION_THREADING to 0.</p>

<p><a name="option"></a><b>The Options</b></p>

<ul>
<li><b>OPTION_TG / --set-tg=...</b> - the text/graphics mode which should be
used for the user interface; the following modes (variants) are currently
supported:
<ul>
<li>curses - a general curses library (using include file &lt;curses.h&gt;,
linking with "-lcurses"); you should try this one if you can't build the
program with the default (ncurses) mode, e.g. because the default (ncurses)
library isn't available on your computer</li>
<li>ncurses - the GNU <a
href="http://directory.fsf.org/ncurses.html">ncurses</a> library (using include
file &lt;ncurses.h&gt;, linking with "-lncurses")</li>
<li>bicurses - a built-in curses emulation for text terminals; this mode
doesn't yet support colors and mouse, and it will never support all possible
combinations of oddities of all existing terminals; if it doesn't work on your
terminal, use a real curses library (it has been tested with the terminal types
"linux", "screen" and "xterm-color" and seems to work with them); it might just
be useful if you don't have enough RAM or (floppy) disk space for a fully-blown
curses library. The terminal type must be given in the environment variable
TERM, as usual. You can provide the environment variable TERMINFO as the path
of a directory which contains the terminfo files, otherwise the standard path
"/usr/share/terminfo/" is used. The usual environment variables COLUMNS and
LINES are respected as explained for xcurses below.</li>
<li>xcurses - a built-in xcurses functionality which opens a window in an <a
href="http://www.x.org/">X Window System</a> environment and emulates a curses
library there. Please note that this mode can be relatively slow due to the
scroll bar calculations; you might want to disable scroll bars with the <a
href="rtconfig.html">run-time configuration option</a> "scroll-bars" or the
keyboard <a href="keymap.html">command action</a> "scroll-bars-flip". - The
usual environment variables COLUMNS and LINES are respected if both are given
and have a value of at least 30 resp. 10; please note that some shells
automatically reset these variables soon after they changed, so you should do
it all in one line like so if necessary: "export COLUMNS=42; export LINES=21;
retawq".</li>
<li>curses:<i>headerfilename</i>:<i>libraryname</i> - for special curses
libraries; fictitious example: "curses:foocurses.h:barcurses" results in using
include file &lt;foocurses.h&gt;, linking with "-lbarcurses"</li>
</ul></li>

<li><b>OPTION_TEXTMODEMOUSE / --enable-textmodemouse</b> - whether you want to
get support for a "text-mode mouse" like <a
href="ftp://arcana.linux.it/pub/gpm/">gpm</a> on text terminals or the mouse
cursor in terminal emulators like xterm (default: 1); this allows you to
activate links (and HTML form elements) by clicking them with the mouse, which
is easier and faster than pressing the Cursor-down/up keys several times. It
depends on your curses library whether you can actually get this support - it's
currently only available if the library provides ncurses-like mouse support
(technobabble: detected by the presence of the C pre-processor symbol
NCURSES_MOUSE_VERSION).</li>

<li><b>OPTION_I18N / --enable-i18n</b> - retawq supports several natural
languages (currently English, French, German, Spanish, Brazilian Portuguese and
Japanese). By default, it uses the English language. If you prefer another
supported language, set this option to "1" / use --enable-i18n, set the option
PATH_INSTALL_LOCALE / --path-locale=... to whatever is appropriate for your
computer, and say "make install" after "make". (Cf. the file <a
href="../INSTALL">INSTALL</a> for details.) retawq uses the "gettext"
functionality to implement this option; some computers have this in their
standard C library, others might require a separate library called "intl"; if
compilation fails, you might have to install such a library or to leave the
feature disabled.</li>

<li><b>OPTION_CED / --set-ced=...</b> - quality of character entity display;
retawq normally tries to print nice characters on the screen for special HTML
character entities like "&amp;agrave;". If your terminal can only handle
seven-bit ASCII characters and shows garbage otherwise, set this to 0.</li>

<li><b>OPTION_NEWS / --enable-news</b> - whether the <a href="scheme.html">URL
schemes</a> "news"/"nntp" for news-reading should be supported (default: 1)

<li><b>OPTION_COOKIES / --enable-cookies</b> - whether cookies should be
supported ("HTTP state management"; default: 1). Cookies are only stored and
sent for servers for which the <a href="rtconfig.html">run-time configuration
option</a> "http-cookies" explicitly allows it.</li>

<li><b>OPTION_LOCAL_CGI / --enable-local-cgi</b> - whether the <a
href="scheme.html">URL scheme</a> "local-cgi" should be supported (default: 0);
local CGI scripts are only executed as explicitly allowed with the <a
href="rtconfig.html">run-time configuration option</a> "local-cgi".
<br><i>Security Note:</i> if you enable this feature, retawq is able to execute
external scripts; such "scripts" can be any kind of executable programs, so it
could also be "viruses" or other malicious software. To avoid unwanted effects,
please observe at least the following hints: 1. You should make sure that
nobody but you can change your config file; otherwise someone might be able to
allow the execution of malicious CGI scripts with the local-cgi feature. So you
should use a command like "chmod go-rwx config" or "chmod go-rwx
/home/<i>your_home</i>/.retawq/"... 2. You should also make sure that nobody
can put malicious scripts into allowed paths or manipulate existing allowed
scripts.</li>

<li><b>OPTION_EXECEXT / --set-execext=...</b> - whether the execution of
external commands should be allowed; if you'd like to execute shell commands
with the <a href="key.html">keyboard command</a> "!", set this option to 1 and
set the <a href="rtconfig.html">run-time configuration option</a>
"execext-shell" as appropriate for the shell program you want to use.
<br><i>Security Note:</i> if you enable this feature, retawq is able to execute
external programs; most of the security information given in the description of
OPTION_LOCAL_CGI above applies here too, respectively. There's a reason why
this option has such an ugly name...</li>

<li><b>OPTION_TLS / --set-tls=...</b> - which variant of <a
href="tls.html">TLS/SSL</a> should be supported (default: 0); this is used for
<a href="scheme.html">URL schemes</a> like "https" and "ftps"</li>

<li><b>OPTION_IPV6 / --enable-ipv6</b> - whether the "next generation" Internet
Protocol version IPv6 should be supported (default: 0); IPv6 can only work if
the libraries and operating system on your computer support it<!-- ; if you
enable this option, the binary becomes only neglectably bigger, but some data
structures might become much bigger (technobabble: using "struct
sockaddr_storage" instead of "struct sockaddr") --></li>

<li><b>OPTION_THREADING / --set-threading=...</b> - which kind of threading
model should be used (default: 1); 0 means that the whole program runs in a
single thread, so all DNS hostname lookups "block" the whole program and it
seems to hang, possibly for many seconds; 1 means that DNS hostname lookups run
in their own thread, using a pthreads (Posix threads) library; 2 means that the
Linux-specific clone() syscall is used (via the standard C library) instead of
pthreads.
<br>You should use 0 only if necessary, e.g. if you build a "whole system on
one floppy disk" with a non-Linux system and don't have enough free space for a
pthreads library. In short: use 1 if at all possible.</li>

<li><b>OPTION_BIRTCFG / --enable-birtcfg</b> - this is a rather special option
which specifies whether a "built-in" <a href="rtconfig.html">run-time
configuration</a> shall be used in addition to (or instead of) external
run-time configuration files; if you enable this, you must prepare the run-time
configuration which shall be built into retawq by running "tool/birtcfg.pl
<i>filename</i>"; the configuration file <i>filename</i> which shall be built
into retawq must not contain any double-quote (") character, neither in the
options nor in comments, because such a character would confuse the C compiler.
The script tool/birtcfg.pl is a Perl script (sorry:-), so you need a <a
href="http://www.perl.com/">Perl</a> interpreter to run it; the script expects
the interpreter at /usr/bin/perl. - The main advantage of a built-in run-time
configuration is that you need not carry external configuration files around. A
disadvantage is that the built-in configuration can't be changed without
rebuilding the program, but you can disable it with the <a
href="arg.html">command-line option</a> "--rtcfg=..." if necessary. To read the
contents of a built-in configuration, visit the <a href="scheme.html">URL</a>
"about:birtcfg" in retawq.</li>

<li><b>CC</b> - the name of the C compiler which is installed on your system;
the default is "<a href="http://directory.fsf.org/gcc.html">gcc</a>", the GNU
compiler collection.</li>

<li><b>CFLAGS</b> - special flags (command-line arguments) for your C compiler;
it should not be necessary to change anything here, but anyway... For
information about possible flags, please read the documentation of your C
compiler.</li>

<li><b>All the other configuration options</b> in the classical Makefile should
stay as they are - some of the respective features have not yet been fully
implemented.</li>
</ul>

<p><a name="mini"></a><b>Minimizing retawq's Size</b></p>

<p>retawq is already a quite small browser. If you want to make the executable
program still smaller, e.g. as a tool for a boot/rescue disk or a "whole system
on one floppy disk" collection, this section shows how to shrink retawq's size
by disabling "all" compile-time configuration options, including some internal
options which aren't documented elsewhere. If you actually need a feature, you
should leave the respective option enabled, of course. The minimization is
shown with the configure script here; you can get the same result by editing
the "classical" Makefile manually.</p>

<p>As a starting point, disable all officially documented options which are
enabled by default: "./configure --disable-textmodemouse --disable-news
--disable-cookies --set-threading=0 --set-ced=0". You could additionally use
"--set-tg=curses" (if that works on your computer) to disable some
ncurses-specific code. - The disabling of multi-threading has the additional
benefit that no pthreads library is necessary.</p>

<p>Now for the "dirty" part: open the file ".config" (which was generated by
the configure script) in a text editor, and do any or all of the following; in
parentheses: effect of the change.</p>
<ul>
<li>set CONFIG_ABOUT to 0 (no "about" <a href="scheme.html">URLs</a> besides
"about:retawq" are supported); or set it to the sum (technobabble: the bit-wise
"or") of the following individual values to leave the respective URLs enabled:
1 for "about:activity", 2 for "about:hostinfo", 4 for "about:ctconfig", 8 for
"about:help".</li>
<li>set CONFIG_BLOAT to 0; CONFIG_BLOAT concerns miscellaneous small pieces in
various parts of the program which add some nice comfort but no "actual"
functionality; you can set it to the sum (technobabble: the bit-wise "or") of
the following individual values to leave the respective pieces enabled: 1: show
human-readable explanations of server status codes in the message line; 2: show
IP addresses in "Connecting to" messages and in "about:hostinfo" documents; 4:
handle the <a href="arg.html">command-line option</a> "--help"; 8: show the
full list of available options with the <a href="arg.html">command-line
option</a> "--help"; <!-- 16: a color-related feature which isn't yet useful
anyway, just disable it; -->32: handle scroll bars (currently relevant for
OPTION_TG=xcurses only); 64: handle the <a href="rtconfig.html">run-time
configuration option</a> "termwintitle"; 256: support colors in general</li>
<li>set CONFIG_CONSOLE to 0 (the console <a href="runmode.html">runmode</a>
isn't available)</li>
<li>set CONFIG_EXTRA to 0; CONFIG_EXTRA concerns miscellaneous pieces in
various parts of the program similiar to CONFIG_BLOAT, but regarding "actual"
functionality; you can set it to the sum (technobabble: the bit-wise "or") of
the following individual values to leave the respective pieces enabled: 1: all
"download" functionality, e.g. the <a href="arg.html">command-line option</a>
"--download" and the <a href="key.html">keyboard commands</a> "D" and "ctrl-d";
2: all "dump" functionality, e.g. the <a href="arg.html">command-line
option</a> "--dump" and the <a href="key.html">keyboard command</a> "d"</li>
<li>set CONFIG_FINGER to 0 (the finger protocol isn't supported)</li>
<li>set CONFIG_FTP to 0 (the FTP protocol isn't supported)</li>
<li>set CONFIG_FTPDIR to 0 (FTP directory listings contain less
information)</li>
<li>set CONFIG_HTTP to 0; CONFIG_HTTP concerns several special HTTP-related
features; you can set it to the sum (technobabble: the bit-wise "or") of the
following individual values to leave the respective features enabled: 1:
support for HTTP/1.1 (otherwise, only HTTP/1.0 is supported); 16: HTTP proxy
authentication (cf. the <a href="rtconfig.html">run-time configuration
options</a> "http-proxies" and "https-proxies")</li>
<li>set CONFIG_JUMPS to 0 (the "jumps" (URL shortcuts) feature isn't
available)</li>
<li>set CONFIG_KEYMAPS to 0 (<a href="keymap.html">keymaps</a> aren't
configurable)</li>
<li>set CONFIG_LOCALDIR to 0 (local directory listings contain less
information, sorting can't be customized)</li>
<li>set CONFIG_MENUS to 0 (no menus are available; especially you can't change
the selections of HTML form &lt;select&gt; tags); or set it to the sum
(technobabble: the bit-wise "or") of the following individual values to leave
the respective menu-related features enabled: 1: contextual menu (e.g. <a
href="key.html">keyboard command</a> "m"); 2: URL history menu (<a
href="key.html">keyboard command</a> "u"); 4: window list menu (<a
href="key.html">keyboard command</a> "ctrl-w"); 8: menu for changing the
selections of HTML form &lt;select&gt; tags</li>
<li>set CONFIG_RTCONFIG to 0 (retawq doesn't handle <a
href="rtconfig.html">run-time configuration</a>, neither a built-in string nor
an external file)</li>
<li>set CONFIG_SESSIONS to 0 (you can't save/resume <a
href="session.html">sessions</a>)</li>
<li>set CONFIG_USER_QUERY to 0 (the resource manager can't ask you
interactively for any login username, password etc.; you have to provide such
information directly in the URL or in <a href="rtconfig.html">run-time
configuration options</a>)</li>
<li>set CONFIG_WK to 0 (no <a href="wk.html">window kind</a> besides "browser
window" is available; especially, the kind "information window" is
disabled)</li>
<li>set HAVE_UNAME to 0 (the number for the <a href="rtconfig.html">run-time
configuration option</a> "user-agent" doesn't have any effect)</li>
<li>add the line "#define DO_NOT_INLINE" (retawq might become slightly slower;
hardly noticeable)</li>
<!-- <li><b>CONFIG_HTML_COLORNAMES</b> - amount of HTML color names which are
known to retawq, as used e.g. in &lt;font color="blue"&gt;...&lt;/font&gt;;
allowed values are:
<br>0 - no color names at all
<br>1 - only the 16 color names which are defined by the HTML specification
<br>2 - the 140 color names which are used by most web browsers (default)
<br>3 - more than 600 color names, just for artists :-)</li> -->
</ul>

<p>Finally, say "make" to build the program. Let's have a look at some
resulting sizes, for example when building version 0.2.6 on the x86 platform,
Linux kernel 2.2.x, libc GNU glibc 2.2.x, compiler GNU gcc 2.7.2.3:</p>
<ul>
<li>74 KB - minimal (but OPTION_TG=ncurses)</li>
<li>129 KB - all "official" options disabled</li>
<li>147 KB - default configuration</li>
<li>177 KB - everything enabled (./configure --enable-i18n --enable-local-cgi
--enable-ipv6 --set-tls=1 --set-execext=1) except "--enable-birtcfg"</li>
</ul>

<p>On my computer, minimal retawq is much smaller than the file viewer "less"
(which has about 90 KB after running "strip --strip-unneeded less"), so you
might even consider removing "less" from your "whole system on one floppy disk"
collection and doing something like "ln -s retawq less". Funny, isn't it?</p>

<p>Newer versions of gcc seem to generate much worse code than the good/bad old
2.7.2.3. For these, you might want to replace the compiler option "-O2" with
"-Os" in the Makefile.</p>

<p><hr>This documentation file is part of version 0.2.6c of <a
href="http://retawq.sourceforge.net/">retawq</a>, a network client created by
<span lang="de">Arne Thoma&szlig;en</span>. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2006 <a href="mailto:arne@arne-thomassen.de"><span
lang="de">Arne Thoma&szlig;en</span></a>.</p>
</body></html>
